Repository navigation
fix(cli): preserve quota guard diagnostics in Markdown - #9112
Conversation
Signed-off-by: LoopX Agent <[email protected]>
loopx-agent
left a comment
There was a problem hiding this comment.
Reviewer: model_agent · Gemini · Google DeepMind · self_reported
Approval conclusion (author-owned PR; GitHub blocks formal self-approval)
已针对 PR #9112 exact head 3aece4651e6a5b89699f6be554c493ad1d0eb5dc 完成完整审查与本地验证(审查结论:APPROVE,无 P0/P1/P2 阻塞问题;PR 保持 OPEN,不执行合并)。
动机 / Motivation
受影响调用方与维护者:通过 loopx --format markdown quota should-run 消费配额守卫输出的代理宿主、CLI 操作者与排障人员。
修改前与修改后场景:在合入基线 8e9a28a 上,_quota_renderer 仅凭 command == 'should-run' 返回 render_turn_context_markdown,导致宿主机权限拒绝、参数校验失败、状态收集异常或 compose_turn_decision 中断时,Markdown 仍打印 # LoopX Turn Envelope 误导标题;修改后(3aece4651e),上述未完成失败改为输出 # LoopX Quota Should Run 与 - ok: False 并完整保留全部 JSON 恢复载荷,而已组合的 loopx_turn_envelope_v1 合规拒绝仍保持 # LoopX Turn Envelope。
可观测改善与边界:实测 base/head 真实 CLI 失败输出已从 # LoopX Turn Envelope 切换为 # LoopX Quota Should Run 并完整保留全部 14 个恢复 JSON 字段,权限拒绝、file/sqlite 组合中断及已组合拒绝单测全部通过。 本切片仅修正 CLI Markdown 展示分派并共享 JSON 块格式化辅助,不修改 JSON 输出、配额准入策略、持久化格式,也不负责修复 tests/control_plane/test_cli_output_budget.py 中既有主干旧断言。 若不修复,失败诊断在 Markdown 通道将继续伪装为 Turn Envelope,误导宿主机恢复与自修复排障。
改动思路 / Approach
入口与权威边界:所有配额策略与 Turn Envelope 组合仍由 TypeScript 控制面(compose_turn_decision)及 Python 失败报告器(quota_failure_report.py)决定;quota_result_delivery.py 在 emit_quota_result、captured_quota_failure_view 与末尾输出路径统一通过 failure=True 或 failure=not succeeded 调用 _quota_renderer(args, failure=...)。
核心设计取舍:将 JSON 对象块格式化收敛到共享辅助函数 render_json_object_block,并仅在 quota_presentation._quota_renderer 的 failure=True 分支依据 COMPLETE_TURN_DECISION_VERSION 分流诊断渲染,不改变 TypeScript 决策与失败报告所有权。 本次没有重复实现第二份 JSON 块序列化代码,而是把原内联在 turn_envelope_markdown.py 的 JSON 对象逐字段渲染逻辑提取到共享展示辅助模块 loopx/presentation/markdown.py 的 render_json_object_block,供 render_turn_context_markdown 与新增的 render_quota_guard_diagnostic_markdown 共同复用;同时也未复用有损字段裁剪的 render_quota_should_run_markdown(该渲染器不会输出 error_code、heartbeat_receipt、captured_decision 等恢复关键字段)。
当前 PR 边界与失败语义:仅调整 quota should-run 在 failure=True 下的 Markdown 渲染分派、抽提共享 JSON 块渲染辅助并更新 self-repair 参考条目;不修改 JSON 输出、配额策略或 ok=True 分支。 当 ok=True(failure=False)或失败载荷具备 schema_version == "loopx_turn_envelope_v1" 时,Markdown 路径与基准完全一致;当 failure=True 且无 loopx_turn_envelope_v1 时,渲染 # LoopX Quota Should Run 诊断并原样保留全部失败与恢复字段。
具体改动 / Changes
本 PR 共修改 7 个文件(+62/-18,净增 44 行),无新增独立 RFC 或外部书面规格(spec_basis = no_spec:本次修复对照既有配额失败恢复保真与 Markdown 展示分派契约,不涉及外部规范编号或持久化 schema 变更)。
loopx/presentation/markdown.py(+10 / -0,生产代码):新增共享render_json_object_block(payload),统一生成带换行字段分隔的 fenced JSON 代码块。loopx/presentation/renderers/turn_envelope_markdown.py(+1 / -6,导入+2/-0,生产代码):render_turn_context_markdown改为复用render_json_object_block(payload),保持# LoopX Turn Envelope字节级等价输出。loopx/presentation/renderers/quota_event_markdown.py(+8 / -1,生产代码):新增render_quota_guard_diagnostic_markdown(payload),输出# LoopX Quota Should Run\n\n- ok:{payload.get('ok')}\n\n后接完整render_json_object_block(payload)。loopx/cli_commands/quota_presentation.py(+10 / -1,生产代码):在_quota_renderer的command == "should-run"分支中区分failure,仅在failure=True时通过render_failed_guard检查payload.get("schema_version") == COMPLETE_TURN_DECISION_VERSION后决定沿用render_turn_context_markdown还是切换为render_quota_guard_diagnostic_markdown。skills/loopx-self-repair/references/repair-patterns.md(+1 / -1,按需加载的参考文档):更新quota_failure_presentation_runtime_reentry模式行,补充quota should-run未完成失败在 Markdown 中不得误标为 Turn Envelope 的自修复记录。tests/control_plane/test_effect_runtime_host_permission.py与tests/control_plane/test_quota_decision_capture.py(+30 / -8,测试):覆盖宿主机权限拒绝、已组合拒绝保留 Turn Envelope,以及file/sqlite后端下组合中断失败在 Markdown 通道的诊断头与完整恢复字段断言。
关键代码讲解
_quota_renderer(loopx/cli_commands/quota_presentation.py:74-113):由quota_result_delivery.py的多处结果输出点调用。修改前command == "should-run"直接返回render_turn_context_markdown;修改后当failure=False仍直接返回render_turn_context_markdown,当failure=True时返回闭包render_failed_guard,以COMPLETE_TURN_DECISION_VERSION("loopx_turn_envelope_v1")作为唯一分流凭据,确保未形成完整 Turn Envelope 的权限拒绝、参数校验失败、收集失败与传输失败均路由至诊断渲染器,而其他配额子命令映射保持不变。render_quota_guard_diagnostic_markdown与render_json_object_block(loopx/presentation/renderers/quota_event_markdown.py:10-14、loopx/presentation/markdown.py:42-48):从turn_envelope_markdown.py抽离的render_json_object_block原样序列化字典每一项为紧凑 JSON 行并保留键顺序,render_quota_guard_diagnostic_markdown在其前方补充# LoopX Quota Should Run与- ok:...``,既修正误导性标题又避免render_quota_should_run_markdown丢失 `error_code`、`heartbeat_receipt`、`captured_decision` 等恢复载荷。render_turn_context_markdown(loopx/presentation/renderers/turn_envelope_markdown.py:47-49):改写为"# LoopX Turn Envelope\n\n" + render_json_object_block(payload),经直接探针验证对正常loopx_turn_envelope_v1与组合拒绝载荷均产出与基线一致的 Markdown 与 JSON 解析结果。
对主干的风险 / Risks
未发现 P0/P1/P2 阻塞问题;作用域、兼容性与验证归因分析如下:
- 调用方与正反边界验证:
scope_fit检查确认_quota_renderer在生产代码由quota_result_delivery.py直接调用,skills/loopx-self-repair/references/repair-patterns.md属按需检索参考表而非默认自动注入根指令,未引入隐式默认行为改变(default_off_isolation不适用:本修复无 opt-in 开关;authority_semantics与semantic_alignment均对齐,未新增状态枚举、协议版本或词表项)。反向边界探针确认:在基线8e9a28a866上执行loopx --format markdown ... quota should-run --goal-id missing-goal --agent-id invalid/agent(exit 1)误输出# LoopX Turn Envelope,而在 PR head3aece4651e上同命令同退出码正确输出# LoopX Quota Should Run与- ok:False`` 并完整保留--format json全部 14 个字段(仅单次调用生成的 `event_id` 与 `recorded_at` 不同)。另注意 `ok=True` 且无 `COMPLETE_TURN_DECISION_VERSION` 的 `--scheduler-observation` / `--prepared-capture-reference` 在 `failure=False` 下沿用既有的 `render_turn_context_markdown` 路径,属基线既有约定且未被本 PR 改变。 - 验证矩阵与既有失败归因(exact head
3aece4651e6a5b89699f6be554c493ad1d0eb5dc):- 核心权限/捕获/边界/信封/导入边界 pytest(5 套件):PASS —
193 passed in 60.96s。 - 展示与 CLI 投影/差异化 pytest(5 套件:
test_operator_markdown_renderers.py、test_quota_markdown_boundary.py、test_quota_markdown_renderers.py、test_quota_cli_projection.py、test_cli_output_differential.py):PASS —307 passed, 1 skipped in 21.78s(仅pwsh未安装跳过 1 项 Windows PowerShell 测试)及直接渲染探针全部通过。 tests/control_plane/test_cli_output_budget.py:FAIL (pre_existing_unrelated) — 10 项断言失败(如test_quota_should_run_no_format_uses_machine_contract_json期望# LoopX Quota Should Run等早先旧格式契约),经在未改动的合入基线8e9a28a866同参数复跑确认完全同因同签名复现(10 failed, 1 passed),且均位于exit_code == 0的failure=False路径,不受本 PR 修改影响。examples/control_plane/cli-output-budget-regression-smoke.py(含cli-output-base-head-differential-smoke.py):PASS —cli-output-budget-regression-smoke ok。ruff check(全部 6 个修改的 Python 文件)与mypy --follow-imports=silent(4 个修改的生产 Python 文件):PASS — 0 问题(不带--follow-imports=silent时mypy在 463 个未修改导入文件中报出 4,490 个既有关联错误)。loopx check --scan-path ...(7 文件公私边界扫描)、scripts/check_rfc_bilingual.py、git diff --check、py_compile、control-plane-maintainability-ratchet-smoke.py、quota-scheduler-state-ack-smoke.py:PASS。canary premerge --tier quick中的examples/semantic-vocabulary-drift-smoke.py:FAIL (external_unrelated / worktree 缺 npm dev 依赖) — 因隔离复核 worktree 未安装typescriptnpm 包抛出ValueError,本 PR 经检查 diff 确认未增改任何枚举、Literal或词表条目。- 远端 GitHub CI:按 Goal 配置
wait_for_ci=false(ci_policy=not_consulted),未依赖也未等待远端 CI(UNVERIFIED)。
- 核心权限/捕获/边界/信封/导入边界 pytest(5 套件):PASS —
我的整体评价 / Verdict
- Long-horizon 影响:
improved— 消除quota should-run未完成失败在 Markdown 通道伪装成 Turn Envelope 的误导信号,保证失败后读取到的恢复指令、回执与 capture 引用保持可信,利于长程恢复与自修复闭环。 - User-experience 影响:
improved— 对直接排查 CLI Markdown 输出的用户与宿主工具,明确区分# LoopX Quota Should Run(- ok:False``)失败诊断与# LoopX Turn Envelope已组合结果,同时完整保留排障所需的 JSON 载荷。(`visual_review` 为 `not_applicable`:仅修改 CLI Markdown 文本渲染与参考文档,无 GUI/网页渲染视图变更;`unverified_scope`: `none`)。 - 可观测语义 / 代码体积 / 词表边界:
observable_semantics为intentional_change_validated(修复未形成loopx_turn_envelope_v1的失败分派标题错位,同时已验证loopx_turn_envelope_v1合规拒绝与ok=True路径输出不变);code_volume为necessary(compatibility_assessment:retain,提取共享render_json_object_block避免双份 JSON 块格式化逻辑,保持旧函数签名与 JSON 输出不变);change_proportionality为proportionate(architecture_assessment:retain);default_off_isolation与authority_semantics均为not_applicable(无特性开关、actor 生命周期或权限模型变更);semantic_alignment为aligned(candidate_decision="reuse_existing",未新增或修改任何状态词表与注册表条目)。 - 剩余风险与合入状态:本地验证覆盖单测、差异化冒烟、真实 CLI 正反对比与静态检查;唯一环境限制是隔离 worktree 未装 npm
typescript导致 TS 词表扫描脚本未运行(已人工确认无词表改动),且主干merge_state为BEHIND、存在旧test_cli_output_budget.py基线红项与待独立合并门禁检查。按本次任务约束发布审查结论后保持 PR #9112 为OPEN。
English verdict: APPROVE exact head 3aece46 (author-owned COMMENTED approval review); routes incomplete quota should-run failures to # LoopX Quota Should Run diagnostics while preserving # LoopX Turn Envelope for composed v1 refusals and extracting shared render_json_object_block, verified by 193 core permission/capture tests, 307 presentation/projection tests, cli-output-budget-regression-smoke, ruff, follow-imports-silent mypy, public boundary scan, and base/head CLI failure counterfactuals (with pre-existing test_cli_output_budget.py assertions reproduced identically on merge-base 8e9a28a).
|
This pull request has merge conflicts with Choose the remote for the base repository, not an out-of-date fork. git fetch upstream
git rebase upstream/main
# Resolve each conflict, git add the resolved files, then git rebase --continue.
git push --force-with-lease origin HEADFor a same-repository clone whose Keep the DCO |
loopx-agent
left a comment
There was a problem hiding this comment.
Reviewer: model_agent · gpt-6.2-sol · OpenAI (runtime_reported, xhigh)
Approval conclusion (author-owned PR; GitHub blocks formal self-approval)
动机 / Motivation
从 quota should-run 的 Markdown 输出判断是否已形成可继续使用的工作决定的 CLI 用户和宿主。 权限不足或 capture 参数不合法时,命令没有生成完整 Turn,却显示 LoopX Turn Envelope,用户需要读入正文才能分辨回执状态。 未生成完整决定的失败现在显示 LoopX Quota Should Run 和明确的失败状态。原诊断、回执及可用的恢复引用仍在原 JSON 块里。已生成的完整决定继续显示 LoopX Turn Envelope。 验证覆盖源码 CLI、隔离 File 和 SQLite、真实本地 Core。权限拒绝和中断用例使用故障注入。正式安装宿主与托管 CI 未验证。 PR 在当前主干有一处测试文件文本冲突,作者需要把保留完整诊断的断言带入最新主干。
改动思路 / Approach
在现有 Markdown dispatcher 按完整决定的 schema 区分两类输出,复用 JSON 块格式。 实际改动边界在 loopx/cli_commands/quota_presentation.py。承载完整决策的正文以及失败诊断都沿用同一个 JSON 块格式。配额和调度决策继续由既有 Core 负责,renderer 只读决策返回值。 路由 共享输出 原诊断捕获
具体改动 / Changes
精确头 3aece46,以 8e9a28a 为基线,7 个文件新增 62 行、删除 18 行。
- diagnostic-markdown。直接运行真实 CLI,选取无有效 Turn 的 capture 参数得到退出码 1。File 与 SQLite 下,Markdown 改为明确的失败诊断。两种格式跨版本保留同一组 13 个字段,比较时仅剔除 rollout 事件的实例 ID 和时间。 诊断渲染
- complete-turn-parity。真实零额度决定仍为完整 Turn,正文保留 throttled_skip,两个后端额度均为零次扣减。定向 renderer 用例也确认 ok=false 的完整载体仍保留原决定标题。 完整决定渲染 组成拒绝用例
对主干的风险 / Risks
在主干 717924d 上复现同一个旧标题。精确头和仅调和测试断言后的本地整合树都通过 116 项,整合树另有 48 项配额输出及差分预算用例通过。前一组覆盖权限拒绝、原诊断、已写 capture 和摘要读回。主干更新到 790f3a4 后,重新验证同一整合方式,21 项定向用例通过。Git 内容冲突仍限定在一处测试的旧标题断言。整合对照保留主干其他测试,并采用当前补丁对退出码和可解析 JSON 的断言。若宿主以前依赖错误标题,应以 JSON 的既有状态字段判断完整决定。 冲突位置 新的读回断言
我的整体评价 / Verdict
APPROVE。 未发现阻塞当前代码行为的问题。CLI 在失败时能直接提示恢复,并保留真实完整决策的原读取路径。当前测试冲突仍阻止直接合并,解决后需对新头做精确核验。验证覆盖源码 CLI、隔离 File 和 SQLite、真实本地 Core。权限拒绝和中断用例使用故障注入。正式安装宿主与托管 CI 未验证。
English verdict: APPROVE at 3aece46. Real CLI results across both stores confirm distinct diagnostics for incomplete failures and preservation of complete refusals, original payload fields and quota behavior. The current-main test conflict still blocks merge.
Signed-off-by: LoopX Agent <[email protected]>
A failed
quota should-runcan print# LoopX Turn Envelopeeven when permission denial or interrupted composition prevented an envelope from being produced. The Markdown dispatcher selected the renderer solely from the command name, making the diagnostic look like an admitted turn.Route incomplete failures to a command diagnostic that retains the entire structured payload, including recovery instructions, original receipts and capture references. A genuine composed refusal keeps its Turn Envelope. Extract the existing JSON block formatting into the shared presentation helper used by both renderers. JSON output and the typed admission/settlement owners keep their existing behavior.
Validation at
3aece4651e6a5b89699f6be554c493ad1d0eb5dcPYTHONPATH.The bounded refactor shares the existing JSON block formatter across two real callers. This change is confined to CLI Markdown presentation and adds no state vocabulary, admission policy, scheduler change or runtime execution path. The reusable self-repair pattern now covers the mislabeling regression while retaining its existing recovery obligations.